The gradebook package is designed to be a one-stop-shop for managing grades for an academic course. The package was designed to reduce the workload, time-costs, paper waste, and administrative burden of grading. The package was designed for use in courses at a liberal arts college, but it can theoretically be applied to any academic setting.

Note that gradebook is currently in BETA release only, and the package creators do not guarantee flawless performance or take responsibility for any mistakes that may result from use of gradebook.

 

Workflow overview

When using gradebook, the overall grading workflow for a course looks something like this:

 

Before the semester begins:

  1. Install the gradebook package.

  2. Setup your course directory.

  3. Setup details for all of your course’s assignments.

  4. Summarize the calendar of assignments calendar and their relative weights for your syllabus.

  5. Setup the roster of students registered for your course.

For each assignment during the semester:.

  1. Grade submissions and save PDF grade reports using an interactive app.

  2. Share grades with students via email.

  3. Repeat for next assignment!

At mid-term and end-of-term:

  1. Share grade reports with each student to ensure students are aware of their progress and any missing assignments.

  2. Quickly calculate mid-term and final grades.

 

Setup

Installation

The gradebook package can be downloaded directly from GitHub:

# Install devtools if needed
if (!require('devtools')) install.packages('devtools')

# Install package
devtools::install_github('ericmkeen/gradebook')

Load into your R session:

library(gradebook)

This vignette was made with gradebook version 0.0.4.5, and will make use of a few other packages:

library(dplyr)
library(ggplot2)
library(gsheet)
library(tidyr)
library(shiny)
library(rstudioapi)

Note that gradebook is currently in BETA release only, and the package creators do not guarantee flawless performance or take responsibility for any mistakes that may result from use of gradebook.

 

Initialize a course

To setup a course for grading with gradebook, set the R working directory to an empty folder where you want to keep your grade files. Open an R script and name it something simple like grade_enst338.R (ENST 338 is the name of the course we will use as an example throughout this vignette).

At the top of that script, load the gradebook package…

library(gradebook)

… then run this command (replacing the course_id input with the name of your own course):

setup_course(course_id = 'ENST_338')

You only ever need to do this ONCE for each course. After you run this line, I suggest commenting it out with a #.

After running this line, you can navigate to your working directory and see that a directory of folders has been created.

We will cover the purpose for each of these folders throughout this tutorial. For now, open up the setup_<course_id>.R file that has been created within your <course_id> directory.

You now have two R scripts open: grade_<course_id>.R and setup_<course_id>.R. These are the only two files you will need for setting up your course in gradebook. In the setup script you will specify all the details for your assignments, so this is where you will do most of your work before the semester begins. Once the semester begins and you are actively managing student rosters and grading assignments, you will be doing all of your work within the grade script.

The next several steps will take place within your setup script.

 

Setup assignments

Write your code for setting up assignments within your setup_<course_id>.R script.

Every graded assignment in the course needs to have details on file. To add an assignment to the course, use the function assignment().

assignment(course_id = 'ENST_338',                     
           assignment_category = 'Readings', 
           assignment_id = 'Week 03 Abstract',
           out_of = 5, 
           due_date = '2024-02-01',
           extra_credit = FALSE,
           share = TRUE, 
           rubric = NULL)

When this command is run, an .RData file with the assignment details is saved to <course_id>/assignments/.

Note that assignment_id must be unique to all other assignment_id’s, even across assignment_category’s.

Also note that the due_date input needs to follow the format shown here: yyyy-mm-dd.

Also note that the rubric input is NULL. This means that, when it comes time to grade this assignment, you will manually specificy a single numerical grade rather than fill out a rubric. (You will have an option to add written feedback, but the assessment record itself will just be a single manually-assigned grade.).

 

Adding a rubric

To add a rubric to an assignment, you need to set up a named list. The names of the list’s element are the standards, and the contents of each element are the grade scale that will be used to assess its respective standard.

 

Grading scales

The gradebook package comes with several built-in grade scales to use or adapt for your own purposes:

Option 1:

data(grade_scale1)
grade_scale1
##   letter percent rubric_slot        description
## 1      F      55           1    Critical issues
## 2      D      65           2        Many issues
## 3      C      75           3 Focus on improving
## 4      B      85           4      Strong / good
## 5      A      95           5             Superb

Option 2:

data(grade_scale2) 
grade_scale2
##   letter percent rubric_slot  description
## 1      F      55           1 Unacceptable
## 2      C      75           3   Incomplete
## 3      A      95           5     Complete

Option 3:

data(grade_scale3) 
grade_scale3
##   letter percent rubric_slot     description
## 1      F      55           1 Critical issues
## 2      C      75           3  Several issues
## 3      A      95           5        No issue

Here’s an example of how one of these grade scales can be customized for your own needs:

grade_scale4 <- grade_scale3
grade_scale4$percent <- c(60, 75, 90)
grade_scale4
##   letter percent rubric_slot     description
## 1      F      60           1 Critical issues
## 2      C      75           3  Several issues
## 3      A      90           5        No issue

 

Rubric structure

Here is an example of how to design a rubric.

rubric <- 
  list('A proper distillation, not an outline or preview' = grade_scale1,
       'Detail-rich' = grade_scale1,
       'All important aspects of the reading are covered' = grade_scale4,
       'Writing is compelling, effective, efficient.' = grade_scale4,
       "Within the word limit."=grade_scale4,
       'Adherence to instructions overall.' = grade_scale4)

Once this list is saved into an object, pass that object to the rubric input within the assignment() command.

When the assignment() command is run, a PDF of the rubric is saved to the folder <course_id>/rubrics/`. The rubric above will look something like this:

 

Advanced rubric formatting

Rubric categories: To organize your rubric content into categories (e.g., “Writing”, “Intellectual content”, or “Visual aids”), you can add a list element with the name of your desired category. The element’s content is simply the character string "category". See the example below.

Bold text: To highlight certain text within the rubric in bold, use the HTML tags <b> and </b>. See the example below.

 

Here is an example of a long, complex rubric with categories as well as advanced formatting, for a group presentation assignment:.

rubric <- list('Substance' = 'category',
               '<b>A strategic and well-crafted distillation/synthesis</b> of the material.' = grade_scale1,
               'Details make it clear that <b>all materials were studied closely and incorporated closely.</b>' = grade_scale4,
               '<b>All important aspects</b> of the reading are covered properly within the word-limit constraints' = grade_scale4,
               '<b>Story & narrative:</b> the talk takes the form of a story, taking the audience on a shared journey. Anecdotes, characters, plot twists, and heart are used throughout' = grade_scale1,
               '<b>Organization overall</b> is intuitive & clear for the audience.' = grade_scale1,
               '<b>First moments:</b> Excellent, engaging, memorable & relevant attention getter, setting the tone for the entire talk.' = grade_scale1,
               '<b>Compelling justification:</b> The audience is made to care about the issue & context first, <b>before any mention</b> of research or science' = grade_scale1,
               '<b>Final moments:</b> clear & memorable summary of points; refers back to thesis/proposed project. Ends with strong take-away/punchline.' = grade_scale1,
               
               'Delivery' = 'category',
               '<b>Preparation:</b> clearly well-prepared, evident in the timing of the talk, familiarity with visual aids and what will be said; no reading off slides.' = grade_scale4,
               '<b>Time allocation:</b> delivered within the allocated time window; time within the talk is allocated strategically. ' = grade_scale4,
               'All group members <b>share speaking load equally</b>.' = grade_scale4,
               '<b>Speech:</b> conversational, sincere, dynamic & compelling; good pace of speech; no trailing off or rambling; no vocal fillers; impactful use of pauses.' = grade_scale1,
               '<b>Language:</b> can articulate meaning clearly through eloquent word choice & premeditated sentences; no unexplained jargon, abbreviations or acronyms.' = grade_scale1,
               '<b>Explanation:</b> Any word/concept that may not be understood is explained, either explicitly or within abundant context, at a level appropriate to audience.' = grade_scale4,
               '<b>Non-verbal delivery:</b> The “Second Conversation”: Attire, composure, & body language reflect sincerity & professionalism, without sacrificing authenticity.' = grade_scale1,
               '<b>Mistakes:</b> mistakes are handled in a graceful & self-forgiving manner; recovery is quick.' = grade_scale1,
               '<b>Energetic, relatable, genuine, poised, confident but vulnerable, at ease</b>' = grade_scale1,
               
               'Visual aids' = 'category',
               '<b>Strategic use:</b> redundancy (if any) between what is spoken and what is displayed is strategic, not used as a crutch for presenting.' = grade_scale4,
               '<b>Design & display:</b> of professional quality, not sloppy or thrown together. Aids prioritize simplicity, clarity, and good design.' = grade_scale4,
               '<b>Text is sparse</b>; no more than 6 bullet points of large text, each spanning one line or less.' = grade_scale4,
               'Any <b>data visualization</b> has been reduced to the simplest possible form, or explained accordingly.' = grade_scale4)

 

Here is the PDF rendering of this rubric:

 

Replicate assignments

You may have an assignment that will be repeated several times throughout the semester, such as a weekly reading assignment or discussion exercise. Each individual deadline needs to have its own assignment on file, but you can expedite the coding of all those assignments using a loop. Here is an example:

deadlines <- c('2024-01-22',
               '2024-01-29',
               '2024-02-03',
               '2024-02-08',
               '2024-02-15')

for(i in 1:length(deadlines)){
  assignment(course_id = 'ENST_338', 
             assignment_category = 'Reading assignments',
             assignment_id = paste0('Week ', i,': Group discussion'),
             out_of = 10,
             due_date = due_dates[i]
             extra_credit = FALSE,
             share = TRUE, 
             rubric = NULL)
}

 

Review set of assignments

To get a list of all the assignments you have on file, use this:

view_assignments('ENST_338')

 

Syllabus plots

Once each and every one of your assignments for the semester is on file, you can create overview plots of the semester’s plan.

 

Assignment weights:

plot_assignment_weights(course_id)

Example output:.

 

Calendar of points:

plot_assignment_calendar(course_id)

Example output:.

 

Setup student roster

Now that assignments are setup, you should be done working with your setup_<course_id>.R file, and you should start building up code in your grade_<course_id>.R file. (You can always return to your setup script and update assignments as needed, but your routine work in that script should be done for now.).

It is also time to start working it’s time for students to register for your class! Once registration has occurred, you are ready to setup your course roster.

The first step is creating a GoogleSheet with info for enrolled students. This GoogleSheet has four mandatory columns: goes_by (the name the student goes by – must be unique to all other namees in course!), first (first name), last (last name), and email (email address). You are welcome to add other columns to this GoogleSheet, but those extra columns will be ignored and all four of those just mentioned must be included.

 

Make sure that the sheet’s Sharing Settings are set to “Anyone with the link can view”, then copy the sharing link to paste into your R script (remember, we are working within the grade_<course_id>.R script from now on.

students_url <- 'https://docs.google.com/spreadsheets/d/1ISxHeEM-noYGNAAG-BEt0zQek94EAX4SZMuwgFXXqew/edit?usp=sharing'
update_roster('ENST_338', students_url) # rerun this each time your googlesheet is changed

The function update_roster() will download the GoogleSheet contents and save a local version of it within your <course_id> directory. Be sure to rerun update_roster() each time your GoogleSheet is changed.

To get a quick view of the students on your roster for a course, use the function view_students():

view_students('ENST_338')
## # A tibble: 6 × 4
##   goes_by first     last          email                      
##   <chr>   <chr>     <chr>         <chr>                      
## 1 Joe     Joseph    Fakerson      joe.fakerson@sewanee.edu   
## 2 Cher    Cherish   Unreal        cher.unreal@sewanee.edu    
## 3 Ringo   Ringerton McFake-me-not ringo.mcfake@sewanee.edu   
## 4 Deb     Debonaire Whozit        deb.whozit@sewanee.edu     
## 5 Hermie  Hermosa   Schupack      hermie.schipack@sewanee.edu
## 6 Eric    Eric      Ezell         ekezell@sewanee.edu

This is a handy tool for prepping a set of email recipients if you wish to email your entire class. For example, you can copy the output of this command:

paste(view_students('ENST_338')$email, collapse=', ')
## [1] "joe.fakerson@sewanee.edu, cher.unreal@sewanee.edu, ringo.mcfake@sewanee.edu, deb.whozit@sewanee.edu, hermie.schipack@sewanee.edu, ekezell@sewanee.edu"

 

Grading

The function grade() launches a Shiny app that lets you grade submissions.

grade()

The app should look similar to the image below, with options in the left sidebar for selecting the course, assignment, and student to grade:

Adjust the sliders on the rubric to provide your assessment, then press Save grade. A notification will appear confirming that the grade was saved. You can then proceed to the next student’s assessment.

Each grade is saved as an individual .RData file in the folder <course_id>/grades. Go check it out. Each grade is also saved as a PDF report of the graded rubric. You can find those renderings in <course_id>/reports/grades.

An example of a PDF grade report:
 

 

Adjusting dimensions

With each new assignment, you will likely want to adjust the dimensions of the PDF report that is generated. Assignments with longer rubrics will need taller PDFs in order to avoid text overcrowding. The grade() function accepts inputs for adjusting these dimensions. The main two are wrap_rubric and pdf_height.

grade(wrap_rubric = 40, 
      pdf_height = 5)

wrap_rubric defines how wide lines (in terms of number of characters) should be in each rubric standard. A larger number means wider width, which may allow the PDF to have the same height without overcrowding. pdf_height defines the height of the PDF, in inches. You can also adjust these settings within the grade() app using the sliders at the bottom of the left side panel.

Suggested workflow:
To settle on an appropriate PDF size for a given assignment, I typically grade one assignment using the grade() defaults, checkout the PDF file, make adjustments within the app using the sliders, re-save the grade (a warning will appear that a grade is already on file for this student-assignment; simply confirm to overwrite the pre-existing grade), and iterate until I am satisfied with the settings. I then make a note of the correct settings for this type of assignment in my R script. For example:

# Settings for reading assignments
grade(wrap_rubric = 45, pdf_height = 4.5)

There are two more dimensions you can adjust, which will become relevant when you begin to add written feedback to your grades (see next section). The wrap_notes input lets you determine the width of text-wrapping for your written feedback (similar to wrap_rubric above). The render_ratio input lets you adjust the vertical ratio of rubric assessment and written feedback. For example, an assignment may have a brief rubric but you write a lot of feedback; in this scenario you would want a small render_ratio of rubric:feedback, e.g., 0.7. In contrast, if an assignment has a very lengthy rubric and you provide minimal written feedback, render_ratio should be larger, e.g., 4 or 5.

 

Check for ungraded assignments

To keep track of students you have and have not already graded for an assignment, press on the “See ungraded students” button near the bottom of the left side panel.

You can also check for ungraded submissions within your R script, using the function view_missing():

view_missing('ENST_338', mode = 'simple')

This function will return the names of students who do not have grades on file for any assignment that is already due, according to the due date specified when the assignment file was created with the assignment() function.

 

Providing written feedback

To provide custom written feedback on an assignment, go to the left sidebar and check the Provide written feedback? box below the assignment dropdown. When you do, options will appear below the rubric in the main panel. Here’s an example:

The text boxes allow you write in custom feedback. As you write, the “Preview” box will update with a preview of what the student will see based on what you have written. Note that the text boxes already have some default language provided, to “get the ball rolling” on the beginning and end of your feedback. You can control what that default language is using the inputs greeting and conclusion in the grade() function:

grade(greeting = "Dear STUDENT,\n\Great presentation! Thank you so much for leading the group into this part of the course with such a strong example.\n",
      conclusion = "\nThank you again, STUDENT.\n\nProf. Ezell",
      wrap_rubric = 50,
      wrap_notes = 100,
      render_ratio = 5,
      pdf_height = 15)

Note that the function will replace any instance of STUDENT (all-caps required) with the name of the student who is currently selected. Also note that written feedback will be reset every time you switch students.

 

Canned comments

Also see that the headers for the feedback boxes mention “canned comments”. This is a reference to a pre-written set of feedback notes that you have the option to feed to the grade() function. The idea is that you often end up providing the same feedback items to multiple students, so why not build up a log of what those common feedback items are, then draw from that log in an efficient way?

To activate this feature, first open a GoogleSheet and draft some canned comments. This sheet needs to have two columns: category (describing the category of feedback. The function currently recognizes two categories of feedback: "content" and "writing") and comment (in which you write your feedback content). Here’s a screenshot of a minimum example:

Once you have the Sheet setup with a comment or two, change the sharing settings so that “Anyone with the Link Can View” and copy the link. Provide that URL link as a character string to the input canned_comments in the grade() command:

grade(canned_comments = 'https://docs.google.com/spreadsheets/d/11SsfrItX4kbwNJ4cmo8wUPiwIy1qhGlpJ-qX5O4iiBM/edit?usp=sharing')

When you re-launch the grading app and check the written feedback checkbox, you should now see dropbown menus for each category occurring in your GoogleSheet:

When you select a canned comment from one of these dropdowns, the preview will show how your feedback is populated.

If you think of a canned comment to add to your GoogleSheet in the midst of grading, simply update your GoogleSheet then return to the grading app and click the “Refresh Comments” button.

Also note that selections of canned comments will be removed each time you switch students.

 

Handling special cases

 

Updating grades

You may wish to alter a grade you have already saved. Simply select the same course, assignment and student, provide your assessment, then re-save the grade. A warning will appear that a grade already exists, but you can confirm that you wish to overwrite that grade.

 

Deleting grades

You may wish to delete a grade due to explorating testing or due to a mistake, such as accidentally selecting the wrong assignment or student before saving grade. To delete grades, navigate to your course’s folder: <course_id>/grades/, find the grade you want to delete, and manually delete the file.

You should also navigate to the PDF reports of the grades, <course_id>/reports/grades/, and delete the PDF file.

 

Late penalties

When a submission is late, you can apply a penalty using the slides in the left sidebar:

 

Use the slider to set the percent penalty, then use the dropbown to specify the reason for the penalty. When you save the grade, a note will appear at the bottom of the PDF report of the grade indicating that a penalty was applied.

You can adjust the dropdown options here using the input penalty_choices in the grade() command:

grade(penalty_choices = c("N/A", 
                          "Late", 
                          "No submission received", 
                          "Behavior", 
                          "Other"))

Note that the slider and dropdown may not reset when you switch to a new student.

 

No submission received

When a student does not submit an assignment and must be given a zero, you can use the method for late penalties, explained above, to apply a 100% penalty and state that the reason was that no submission was received.

 

Exemptions from assignment

If a student needs to be exempted from an assignment, such that no score is given and the assignment does not count towards the total points used to calculate their final grade, click on the slider labeled “Exempt this student?” in the left sidebar, then press “Save grade”. A grade file will be produced for this student-assignment, in which it will be indicated that the student has an exemption. PDF grade reports are not created for exempt grades.

 

Extra credit

If a student earns extra credit on an assignment, you can apply extra credit as a percentage using the slider in the left sidebar labelled “Apply % extra credit”.

 

Re-rendering grade PDF’s

At some point you may wish to re-render the PDF’s for a set of grades for a particular assignment. Reasons can vary, but perhaps you realize that you want to change the dimensions, word-wrap settings, or rubric:feedback ratio in the PDF. You can do so without touching the original garde files by using the function render_grades():

render_grades(course_id = 'ENST_338',
              assignment_id = 'Presentation',
              render_ratio =  4,
              pdf_height = 7)

 

Sending out grades

To use this feature of gradebook, your computer must be setup to use the R package gmailr, which allows you to send Gmail messages directly from R using functions in gradebook.

 

Setting up gmailr

This can be a tricky process. Follow the instructions here, which will also ask you to follow directions here. The goals of the process are…

  1. to setup your Gmail account to permit external services, such as R, to send emails through the Gmail API,

  2. to download a credentials .json file that is your passkey to accessing the API, and

  3. telling gradebook where to find that credentials .json file.

 

Once you believe you have gmailr up and running, send yourself a test email using the gradebook function email_test().

email_test(
  recipient,
  your_email,
  intro = "Dear STUDENT,",
  signoff = "Best wishes,\nProf. Ezell",
  email_body = "This is a test email using the gradebook R package.",
  json_path = '/Users/fake/fake/fake/credentials.json')

Put your own email in the recipient input and the your_email input.

When you run this command, you will likely be asked by the R console to be taken to a browser where you can select the Gmail account you wish to use, sign into it, and give permissions for gmailr to use your account.

If that function works, and if you receive the test email, and if you see that you sent that email yourself within your Sent tab in Gmail, then you should be firing on all cylinders.

 

Check for unshared grades

Each grade file keeps track of whether or not it has been shared by email with its respective student. To get a snapshot of grades that still need to be emailed out, use;

view_unshared('ENST_338')

 

Emailing grades

To send out grade emails, use the function email_grades().

email_grades(course_id = 'ENST_338',
             your_email = 'ekezell@sewanee.edu',
             intro = 'Dear STUDENT,',
             signoff = 'Best wishes,\nProf. Ezell',
             email_body =  "Attached you will find your grade on this assignment.",
             exempt_body = "This email is a confirmation that you were exempt from this assignment.",
             mode = 'test',
             json_path = '/Users/fake/fake/fake/credentials.json')

This function can operate in one of three modes:

  1. "test" (the default) will simulate sending emails without doing so, instead printing the messages and attachments to the console for your review. (Note that in test mode, you do not need to provide a json file, and the grade’s “shared” status will not change – this is a handy way to exlore the function’s features without committing anything you can’t rescind!).

  2. "draft" will prepare draft messages instead of sent emails, allowing you to go into Gmail and review or modify the draft messages before sending. (Note that in draft mode, each grade will be marked as “shared”!)

  3. "send" will actually send the emails.

As you start out in gradebook, we recommend beginning with test, then graduating to draft and going to Gmail to actually commit to sending the drafted emails. Once you are very confident in how the function works, you can consider going into send mode.

When you run this command in either draft or send mode, the function will…

  1. first ask for confirmation that you want to continue, after showing you a list of the grades that would be shared.

  2. ask for you to select/authorize the email account you want to use to send the email.

  3. then send each email, printing a confirmation to the Console with each email sent.

The email will have a subject line that specifies which assignment_id this grade is for, and it will contain the PDF of the graded rubric (with written feedback, if you provided any) as an attachment. If the student is exempted from the assignment, the exempt_body input will be used instead of the email_body input.

After the loop is complete, re-run the view_unshared() command above to ensure that no more grades need to be shared.

 

Summary reports

The gradebook() currently has two functions for summarizing the grades you have on file. One generates a report for a single student (render_student()), and the other generates a report summarizing current grades for the entire roster (render_class()). The former is most useful when you are looking into the performance of a single student (e.g., during a one-on-one meeting), and latter is useful to get a sense of how the entire class is doing and – at the end of the semester – to quickly calculate final grades.

 

Student reports

To get a report on how a single student is doing, use the function render_student().

render_student('ENST_338',
               'Cassie',
               to_file = FALSE,
               gg_height = 8)

This function will produce a two-pane plot of the student’s grade history for your course. Here’s an example (note that the student’s name has been anonymized using the render_student() input anonymize):

 

By default, this report is simply displayed within R, but you can save these reports to file by changing the input to_file to TRUE. These reports are saved within <course_id>/reports/students/. The date on which you have generated the report is included in the filename. To modify the height (and crowdedness) of the PDF that is generated, alter the input gg_height (the default is 10 inches).

The render_student() function includes an input option named drop_lowest(). This is used to drop the lowest grade in a category of assignments, such as a weekly reading quiz, if this is a policy you use in your course. Simply provide the name(s) of assignment_category’s for which the lowest grade (or one of the missing grades for a student) should be dropped.

To render reports for all students at once, you can use the wrapper function render_students(). This is handy for mid-semester check-ins with every student.

render_students('ENST_338')

Note that for render_students(), the to_file default is TRUE so that each report is saved into your directory.

To email a report to each student individually, you can use the function email_student_reports().

email_student_reports(
  course_id,
  your_email,
  student_id = NULL,
  report_date = lubridate::ymd(lubridate::date(Sys.time())),
  intro = "Dear STUDENT,",
  signoff = "Best wishes,\nYour professor",
  email_body = "Attached you will find a report indicating your overall grade in the course to date. Please review this and reply to me with any questions or concerns.",
  mode = "test",
  json_path = '/Users/fake/fake/fake/credentials.json')

Like the email_grades() function above, this function can operate in one of three modes:

  1. "test" (the default) will simulate sending emails without doing so, instead printing the messages and attachments to the console for your review. (Note that in test mode, you do not need to provide a json file).

  2. "draft" will prepare draft messages instead of sent emails, allowing you to go into Gmail and review or modify the draft messages before sending.

  3. "send" will actually send the emails.

As you start out in gradebook, we recommend beginning with test, then graduating to draft and going to Gmail to actually commit to sending the drafted emails. Once you are very confident in how the function works, you can consider going into send mode.

 

Class reports

To get a report of the entire class altogether – for example to compute mid-term or final grades – use the function render_class().

render_class('ENST_338')

This function returns a list with 2 slots: $plot, which is a plot of all students’ current grade in the course, and $grades, which is a data.frame() of those final grades.

Example of the plot (with names made anonymous, using the render_class() input anonymize):

Example of the table:

This function accounts for all exempt grades on file, and the final grades are based on assignments that are already past their due date. If a student already has a grade for a submission not yet due (perhaps they turned it in early and you’ve already graded it), then that grade will also be included in that student’s final grade calculation (but in other students’).

Note that render_class has several optional inputs:

render_class(course_id, 
             drop_lowest = NULL, 
             apply_curve = 0, 
             letter_key = 'default')

  • The input option drop_lowest() is used to drop the lowest grade in a category of assignments, such as a weekly reading quiz, if this is a policy you use in your course. Simply provide the name(s) of assignment_category’s for which the lowest grade (or one of the missing grades for a student) should be dropped.

  • The input option apply_curve lets you apply a blanket percentage adjustment to all students equally.

  • The input option letter_key lets you provide a “key” that tells gradebook how to translate a percentage grade into a letter grade. If you don’t provide one yourself, the package’s default key will be used:

data(letter_grade_key)

letter_grade_key
##    letter_basic letter_detail grade_floor
## 1             A            A+          97
## 2             A            A           93
## 3             A            A-          90
## 4             B            B+          87
## 5             B            B           83
## 6             B            B-          80
## 7             C            C+          77
## 8             C            C           73
## 9             C            C-          70
## 10            D            D+          67
## 11            D            D           63
## 12            D            D-          60
## 13            F            F         -Inf

If you provide a custom key yourself, it must be in the same format as the built-in dataset above.

 

Conclusion: the routine

Once you get to this point of gradebook setup, in which your course is setup with all its assignments and roster and you have the email features operational, you are ready to settle into the grading routine of the semester. For me, that workflow routine tends to involve these steps.

  1. Make sure gradebook is loaded and your working directory is set to your grading folder.

  2. Run grade() to grade new submissions, checking the PDFs being saved into <course_id>/reports/grades to review formatting, and adjusting PDF formatting settings within the grading app as needed. I tend to end up having a different grade() command for each assignment_id, or at least every assignment_category, since I usually want to customize PDf sizes and feedback greetings/conclusions and URL’s for canned comments.

  3. Check view_unshared() to see which grades need to be emailed out.

  4. Run email_grades() to send out emails.

  5. Every once and a while, review the current grade distribution of the class (render_class()).

  6. When students meet with me or write to inquire about their grade, I check their grade history with render_student(). Two weeks before mid-term and again before the end of term, email out grade reports so that students know where they stand and can check my work for issues or mistakes.

This workflow is all documented within the grade_<course_id>.R script I maintain for the course, so that it is easy for me to re-run certain lines of code whenever I need to.